home *** CD-ROM | disk | FTP | other *** search
/ Scene Storm / Scene Storm - Volume 1.iso / coding / tools / gcc / gcc270_doc.lha / gnu / man / cat1 / cccp.0 < prev    next >
Encoding:
Text File  |  1995-08-24  |  19.7 KB  |  463 lines
  1.  
  2.  
  3.  
  4. cpp(1)                      GNU Tools                      cpp(1)
  5.  
  6.  
  7. NNAAMMEE
  8.        cccp, cpp - The GNU C-Compatible Compiler Preprocessor.
  9.  
  10. SSYYNNOOPPSSIISS
  11.        ccccccpp   [--$$] [--AA_p_r_e_d_i_c_a_t_e[((_v_a_l_u_e))]] [--CC]
  12.               [--DD_n_a_m_e[==_d_e_f_i_n_i_t_i_o_n]] [--ddDD] [--ddMM] [--II _d_i_r_e_c_t_o_r_y]
  13.               [--HH] [--II--] [--iimmaaccrrooss _f_i_l_e] [--iinncclluuddee _f_i_l_e]
  14.               [--iiddiirraafftteerr _d_i_r] [--iipprreeffiixx _p_r_e_f_i_x]
  15.               [--iiwwiitthhpprreeffiixx _d_i_r] [--llaanngg--cc] [--llaanngg--cc++++]
  16.               [--llaanngg--oobbjjcc] [--llaanngg--oobbjjcc++++] [--lliinntt] [--MM [--MMGG]]
  17.               [--MMMM [--MMGG]] [--MMDD _f_i_l_e ] [--MMMMDD _f_i_l_e ] [--nnoossttddiinncc]
  18.               [--nnoossttddiinncc++++] [--PP] [--ppeeddaannttiicc] [--ppeeddaannttiicc--eerrrroorrss]
  19.               [--ttrraaddiittiioonnaall] [--ttrriiggrraapphhss] [--UU_n_a_m_e] [--uunnddeeff]
  20.               [--WWttrriiggrraapphhss] [--WWccoommmmeenntt] [--WWaallll] [--WWttrraaddiittiioonnaall]
  21.               [_i_n_f_i_l_e|--] [_o_u_t_f_i_l_e|--]
  22.  
  23. DDEESSCCRRIIPPTTIIOONN
  24.        The C preprocessor is a _m_a_c_r_o _p_r_o_c_e_s_s_o_r that is used auto-
  25.        matically  by the C compiler to transform your program be-
  26.        fore actual compilation.  It is called a  macro  processor
  27.        because  it  allows  you to define _m_a_c_r_o_s, which are brief
  28.        abbreviations for longer constructs.
  29.  
  30.        The C preprocessor provides four separate facilities  that
  31.        you can use as you see fit:
  32.  
  33.        +o      Inclusion of header files.  These are files of dec-
  34.               larations that can be substituted  into  your  pro-
  35.               gram.
  36.  
  37.        +o      Macro  expansion.  You can define _m_a_c_r_o_s, which are
  38.               abbreviations for arbitrary fragments  of  C  code,
  39.               and then the C preprocessor will replace the macros
  40.               with their definitions throughout the program.
  41.  
  42.        +o      Conditional compilation.  Using special preprocess-
  43.               ing directives, you can include or exclude parts of
  44.               the program according to various conditions.
  45.  
  46.        +o      Line control.  If you use a program to  combine  or
  47.               rearrange  source  files  into an intermediate file
  48.               which is then compiled, you can use line control to
  49.               inform the compiler of where each source line orig-
  50.               inally came from.
  51.  
  52.        C preprocessors vary in some details.  For a full explana-
  53.        tion  of  the  GNU  C  preprocessor,  see  the  iinnffoo  file
  54.        `ccpppp..iinnffoo', or the manual _T_h_e  _C  _P_r_e_p_r_o_c_e_s_s_o_r.   Both  of
  55.        these  are  built from the same documentation source file,
  56.        `ccpppp..tteexxiinnffoo'.  The GNU C preprocessor provides a superset
  57.        of the features of ANSI Standard C.
  58.  
  59.        ANSI  Standard  C  requires the rejection of many harmless
  60.        constructs commonly used by today's C programs.  Such  in-
  61.  
  62.  
  63.  
  64. GNU Tools                   30apr1993                           1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. cpp(1)                      GNU Tools                      cpp(1)
  71.  
  72.  
  73.        compatibility  would be inconvenient for users, so the GNU
  74.        C preprocessor is configured to accept these constructs by
  75.        default.   Strictly  speaking, to get ANSI Standard C, you
  76.        must  use   the   options   `--ttrriiggrraapphhss',   `--uunnddeeff'   and
  77.        `--ppeeddaannttiicc',  but  in  practice the consequences of having
  78.        strict ANSI Standard C make it undesirable to do this.
  79.  
  80.        Most often when you use the C preprocessor  you  will  not
  81.        have  to  invoke  it explicitly: the C compiler will do so
  82.        automatically.  However,  the  preprocessor  is  sometimes
  83.        useful individually.
  84.  
  85.        When  you  call the preprocessor individually, either name
  86.        (ccpppp or ccccccpp) will do--they are completely synonymous.
  87.  
  88.        The C preprocessor expects two file  names  as  arguments,
  89.        _i_n_f_i_l_e and _o_u_t_f_i_l_e.  The preprocessor reads _i_n_f_i_l_e togeth-
  90.        er with any other files it specifies with `##iinncclluuddee'.  All
  91.        the  output generated by the combined input files is writ-
  92.        ten in _o_u_t_f_i_l_e.
  93.  
  94.        Either _i_n_f_i_l_e or _o_u_t_f_i_l_e may be `--', which as _i_n_f_i_l_e means
  95.        to  read from standard input and as _o_u_t_f_i_l_e means to write
  96.        to standard output.  Also, if _o_u_t_f_i_l_e or both  file  names
  97.        are  omitted,  the  standard output and standard input are
  98.        used for the omitted file names.
  99.  
  100. OOPPTTIIOONNSS
  101.        Here is a table of command options accepted by the C  pre-
  102.        processor.  These options can also be given when compiling
  103.        a C program; they are passed along  automatically  to  the
  104.        preprocessor when it is invoked by the compiler.
  105.  
  106.        --PP     Inhibit  generation  of  `##'-lines with line-number
  107.               information in the output  from  the  preprocessor.
  108.               This  might be useful when running the preprocessor
  109.               on something that is not C code and will be sent to
  110.               a program which might be confused by the `##'-lines.
  111.  
  112.        --CC     Do not discard comments: pass them through  to  the
  113.               output  file.  Comments appearing in arguments of a
  114.               macro call will be copied to the output before  the
  115.               expansion of the macro call.
  116.  
  117.        --ttrraaddiittiioonnaall
  118.               Try  to imitate the behavior of old-fashioned C, as
  119.               opposed to ANSI C.
  120.  
  121.        --ttrriiggrraapphhss
  122.               Process ANSI standard  trigraph  sequences.   These
  123.               are  three-character  sequences,  all starting with
  124.               `????', that are defined by ANSI C to stand for  sin-
  125.               gle characters.  For example, `????//' stands for `\\',
  126.               so `''????//nn''' is a character constant for a  newline.
  127.  
  128.  
  129.  
  130. GNU Tools                   30apr1993                           2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. cpp(1)                      GNU Tools                      cpp(1)
  137.  
  138.  
  139.               Strictly  speaking, the GNU C preprocessor does not
  140.               support all programs  in  ANSI  Standard  C  unless
  141.               `--ttrriiggrraapphhss'  is  used,  but if you ever notice the
  142.               difference it will be with relief.
  143.  
  144.               You don't want to know any more about trigraphs.
  145.  
  146.        --ppeeddaannttiicc
  147.               Issue warnings required by the ANSI C  standard  in
  148.               certain  cases  such as when text other than a com-
  149.               ment follows `##eellssee' or `##eennddiiff'.
  150.  
  151.        --ppeeddaannttiicc--eerrrroorrss
  152.               Like `--ppeeddaannttiicc', except that errors  are  produced
  153.               rather than warnings.
  154.  
  155.        --WWttrriiggrraapphhss
  156.               Warn  if  any  trigraphs  are encountered (assuming
  157.               they are enabled).
  158.  
  159.        --WWccoommmmeenntt
  160.  
  161.        --WWccoommmmeennttss
  162.               Warn whenever a comment-start sequence `//**' appears
  163.               in a comment.  (Both forms have the same effect).
  164.  
  165.        --WWaallll  Requests  both  `--WWttrriiggrraapphhss'  and `--WWccoommmmeenntt' (but
  166.               not `--WWttrraaddiittiioonnaall').
  167.  
  168.        --WWttrraaddiittiioonnaall
  169.               Warn about certain constructs that  behave  differ-
  170.               ently in traditional and ANSI C.
  171.  
  172.        --II _d_i_r_e_c_t_o_r_y
  173.                Add the directory _d_i_r_e_c_t_o_r_y to the end of the list
  174.               of directories to be  searched  for  header  files.
  175.               This  can be used to override a system header file,
  176.               substituting your own version, since these directo-
  177.               ries are searched before the system header file di-
  178.               rectories.  If you use more than one  `--II'  option,
  179.               the directories are scanned in left-to-right order;
  180.               the standard system directories come after.
  181.  
  182.        --II--    Any directories specified with `--II' options  before
  183.               the  `--II--' option are searched only for the case of
  184.               `##iinncclluuddee _f_i_l_e"'; they are not searched  for  `##iinn--
  185.               cclluuddee <<_f_i_l_e>'.
  186.  
  187.               If  additional  directories are specified with `--II'
  188.               options after  the  `--II--',  these  directories  are
  189.               searched for all `##iinncclluuddee' directives.
  190.  
  191.               In  addition,  the `--II--' option inhibits the use of
  192.               the current directory as the first search directory
  193.  
  194.  
  195.  
  196. GNU Tools                   30apr1993                           3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. cpp(1)                      GNU Tools                      cpp(1)
  203.  
  204.  
  205.               for  `##iinncclluuddee  _f_i_l_e"'.  Therefore, the current di-
  206.               rectory is searched only if it is requested explic-
  207.               itly  with  `--II..'.  Specifying both `--II--' and `--II..'
  208.               allows you to control precisely  which  directories
  209.               are  searched  before the current one and which are
  210.               searched after.
  211.  
  212.        --nnoossttddiinncc
  213.               Do not search the standard system  directories  for
  214.               header files.  Only the directories you have speci-
  215.               fied with `--II' options (and the current  directory,
  216.               if appropriate) are searched.
  217.  
  218.        --nnoossttddiinncc++++
  219.               Do  not search for header files in the C++ specific
  220.               standard directories, but do still search the other
  221.               standard  directories.   (This  option is used when
  222.               building libg++.)
  223.  
  224.        --DD _n_a_m_e
  225.                Predefine _n_a_m_e as a macro, with definition `11'.
  226.  
  227.        --DD _n_a_m_e==_d_e_f_i_n_i_t_i_o_n
  228.                Predefine _n_a_m_e as a macro, with definition _d_e_f_i_n_i_-
  229.               _t_i_o_n.  There are no restrictions on the contents of
  230.               _d_e_f_i_n_i_t_i_o_n, but if you are invoking the  preproces-
  231.               sor from a shell or shell-like program you may need
  232.               to use the shell's quoting syntax to protect  char-
  233.               acters  such  as  spaces that have a meaning in the
  234.               shell syntax.  If you use more than  one  `--DD'  for
  235.               the  same  _n_a_m_e, the rightmost definition takes ef-
  236.               fect.
  237.  
  238.        --UU _n_a_m_e
  239.                Do not predefine _n_a_m_e.  If both `--UU' and `--DD'  are
  240.               specified for one name, the `--UU' beats the `--DD' and
  241.               the name is not predefined.
  242.  
  243.        --uunnddeeff Do not predefine any nonstandard macros.
  244.  
  245.        --AA _n_a_m_e_(vvaalluuee_)
  246.               Assert (in the same way as the  ##aasssseerrtt  directive)
  247.               the  predicate _n_a_m_e with tokenlist _v_a_l_u_e.  Remember
  248.               to escape or quote the parentheses on shell command
  249.               lines.
  250.  
  251.               You  can use `--AA--' to disable all predefined asser-
  252.               tions; it also undefines all predefined macros.
  253.  
  254.        --ddMM    Instead of outputting the result of  preprocessing,
  255.               output  a  list of `##ddeeffiinnee' directives for all the
  256.               macros defined during the execution of the  prepro-
  257.               cessor,  including  predefined  macros.  This gives
  258.               you a way of finding out what is predefined in your
  259.  
  260.  
  261.  
  262. GNU Tools                   30apr1993                           4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. cpp(1)                      GNU Tools                      cpp(1)
  269.  
  270.  
  271.               version  of  the preprocessor; assuming you have no
  272.               file `ffoooo..hh', the command
  273.  
  274.               touch foo.h; cpp -dM foo.h
  275.  
  276.               will show the values of any predefined macros.
  277.  
  278.        --ddDD    Like `--ddMM' except in two respects: it does _n_o_t  in-
  279.               clude  the  predefined  macros, and it outputs _b_o_t_h
  280.               the `##ddeeffiinnee' directives and the result of  prepro-
  281.               cessing.   Both  kinds of output go to the standard
  282.               output file.
  283.  
  284.  
  285.        --MM [--MMGG]
  286.               Instead of outputting the result of  preprocessing,
  287.               output  a rule suitable for mmaakkee describing the de-
  288.               pendencies of the main source file.  The preproces-
  289.               sor  outputs  one  mmaakkee  rule containing the object
  290.               file name for that source file, a  colon,  and  the
  291.               names of all the included files.  If there are many
  292.               included files then the rule is split into  several
  293.               lines using `\\'-newline.
  294.  
  295.               `--MMGG'  says to treat missing header files as gener-
  296.               ated files and assume they live in the same  direc-
  297.               tory  as  the source file.  It must be specified in
  298.               addition to `--MM'.
  299.  
  300.               This feature is used in automatic updating of make-
  301.               files.
  302.  
  303.        --MMMM [--MMGG]
  304.               Like  `--MM' but mention only the files included with
  305.               `##iinncclluuddee "_f_i_l_e"'.  System  header  files  included
  306.               with `##iinncclluuddee <_f_i_l_e>' are omitted.
  307.  
  308.        --MMDD _f_i_l_e
  309.               Like `--MM' but the dependency information is written
  310.               to `_f_i_l_e'.  This is in addition  to  compiling  the
  311.               file  as specified--`--MMDD' does not inhibit ordinary
  312.               compilation the way `--MM' does.
  313.  
  314.               When invoking gcc, do not specify the `_f_i_l_e'  argu-
  315.               ment.  Gcc will create file names made by replacing
  316.               `..cc' with `..dd' at the end of the input file  names.
  317.  
  318.               In Mach, you can use the utility mmdd to merge multi-
  319.               ple files into a single  dependency  file  suitable
  320.               for using with the `mmaakkee' command.
  321.  
  322.        --MMMMDD _f_i_l_e
  323.               Like  `--MMDD'  except mention only user header files,
  324.               not system header files.
  325.  
  326.  
  327.  
  328. GNU Tools                   30apr1993                           5
  329.  
  330.  
  331.  
  332.  
  333.  
  334. cpp(1)                      GNU Tools                      cpp(1)
  335.  
  336.  
  337.        --HH     Print the name of each header file used,  in  addi-
  338.               tion to other normal activities.
  339.  
  340.        --iimmaaccrrooss _f_i_l_e
  341.                 Process  _f_i_l_e  as input, discarding the resulting
  342.               output, before processing the regular  input  file.
  343.               Because  the output generated from _f_i_l_e is discard-
  344.               ed, the only effect of `--iimmaaccrrooss _f_i_l_e' is  to  make
  345.               the macros defined in _f_i_l_e available for use in the
  346.               main input.  The preprocessor  evaluates  any  `--DD'
  347.               and  `--UU'  options  on the command line before pro-
  348.               cessing `--iimmaaccrrooss _f_i_l_e' .
  349.  
  350.        --iinncclluuddee _f_i_l_e
  351.               Process _f_i_l_e as input, and include all the  result-
  352.               ing  output,  before  processing  the regular input
  353.               file.
  354.  
  355.        --iiddiirraafftteerr _d_i_r
  356.                Add the directory _d_i_r to the second include  path.
  357.               The  directories  on  the  second  include path are
  358.               searched when a header file is not found in any  of
  359.               the  directories  in the main include path (the one
  360.               that `--II' adds to).
  361.  
  362.        --iipprreeffiixx _p_r_e_f_i_x
  363.                 Specify  _p_r_e_f_i_x  as  the  prefix  for  subsequent
  364.               `--iiwwiitthhpprreeffiixx' options.
  365.  
  366.        --iiwwiitthhpprreeffiixx _d_i_r
  367.                 Add  a directory to the second include path.  The
  368.               directory's name is made  by  concatenating  _p_r_e_f_i_x
  369.               and _d_i_r, where _p_r_e_f_i_x was specified previously with
  370.               `--iipprreeffiixx'.
  371.  
  372.        --llaanngg--cc
  373.  
  374.        --llaanngg--cc++++
  375.  
  376.        --llaanngg--oobbjjcc
  377.  
  378.        --llaanngg--oobbjjcc++++
  379.               Specify the source language.  `--llaanngg--cc++++' makes the
  380.               preprocessor  handle  C++  comment  syntax, and in-
  381.               cludes extra default include directories  for  C++,
  382.               and  `--llaanngg--oobbjjcc' enables the Objective C `##iimmppoorrtt'
  383.               directive.  `--llaanngg--cc' explicitly turns off both  of
  384.               these  extensions, and `--llaanngg--oobbjjcc++++' enables both.
  385.  
  386.               These options are generated by the compiler  driver
  387.               ggcccc, but not passed from the `ggcccc' command line.
  388.  
  389.        --lliinntt  Look  for  commands to the program checker lliinntt em-
  390.               bedded in  comments,  and  emit  them  preceded  by
  391.  
  392.  
  393.  
  394. GNU Tools                   30apr1993                           6
  395.  
  396.  
  397.  
  398.  
  399.  
  400. cpp(1)                      GNU Tools                      cpp(1)
  401.  
  402.  
  403.               `##pprraaggmmaa  lliinntt'.   For  example,  the  comment  `//**
  404.               NNOOTTRREEAACCHHEEDD **//' becomes `##pprraaggmmaa lliinntt NOTREACHED'.
  405.  
  406.               This option is available only when you call ccpppp di-
  407.               rectly; ggcccc will not pass it from its command line.
  408.  
  409.        --$$     Forbid the use of `$$' in identifiers.  This is  re-
  410.               quired  for  ANSI  conformance.   ggcccc automatically
  411.               supplies this option to  the  preprocessor  if  you
  412.               specify `--aannssii', but ggcccc doesn't recognize the `--$$'
  413.               option itself--to use it without the other  effects
  414.               of  `--aannssii', you must call the preprocessor direct-
  415.               ly.
  416.  
  417. SSEEEE AALLSSOO
  418.        `CCpppp' entry in iinnffoo; _T_h_e _C _P_r_e_p_r_o_c_e_s_s_o_r, Richard M. Stall-
  419.        man.
  420.        ggcccc(11); `GGcccc' entry in iinnffoo; _U_s_i_n_g _a_n_d _P_o_r_t_i_n_g _G_N_U _C_C _(_f_o_r
  421.        _v_e_r_s_i_o_n _2_._0_), Richard M. Stallman.
  422.  
  423. CCOOPPYYIINNGG
  424.        Copyright (c) 1991, 1992, 1993 Free  Software  Foundation,
  425.        Inc.
  426.  
  427.        Permission  is  granted  to  make  and distribute verbatim
  428.        copies of this manual provided the  copyright  notice  and
  429.        this permission notice are preserved on all copies.
  430.  
  431.        Permission is granted to copy and distribute modified ver-
  432.        sions of this manual under  the  conditions  for  verbatim
  433.        copying,  provided  that the entire resulting derived work
  434.        is distributed under the  terms  of  a  permission  notice
  435.        identical to this one.
  436.  
  437.        Permission  is granted to copy and distribute translations
  438.        of this manual into another language, under the above con-
  439.        ditions for modified versions, except that this permission
  440.        notice may be included in  translations  approved  by  the
  441.        Free  Software  Foundation  instead of in the original En-
  442.        glish.
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460. GNU Tools                   30apr1993                           7
  461.  
  462.  
  463.